home *** CD-ROM | disk | FTP | other *** search
/ Amiga GIGA Graphic / Amiga GIGA Graphic CDs 1-4 (1994)(Geuther)(Disc 3 of 4)[!].iso / libs / xprquickb.doc < prev    next >
Text File  |  1994-03-30  |  8KB  |  196 lines
  1. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  2. /* |_o_o|\\ Copyright (c) 1990 The Software Distillery.  All Rights Reserved */
  3. /* |. o.| || This program may not be distributed without the permission of   */
  4. /* | .    | || the authors:                  BBS: (919) 382-8265    */
  5. /* | o    | ||   Dave Baker      Alan Beale      Jim Cooper             */
  6. /* |  . |//    Jay Denebeim    Bruce Drake      Gordon Keener          */
  7. /* ======      John Mainwaring Andy Mercier      Jack Rouse             */
  8. /*           John Toebes     Mary Ellen Toebes  Doug Walker  Mike Whitcher */
  9. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  10.  
  11. Trademarks
  12.  
  13. Amiga is a trademark of Commodore-Amiga, Inc.
  14. A-Talk III is a trademark of Felsina Software.
  15. Lattice is a trademark of Lattice, Inc.
  16.  
  17.  
  18. Introduction
  19.  
  20. The XprQuickB shared library supports an external file transfer
  21. protocol (XPR) for Amiga programs such as VLT and A-Talk III.  It
  22. supports the Quick B protocol developed and used by CompuServe
  23. Incorporated as an enhancement of their B protocol.  Generally,
  24. Quick B protocol file transfers are significantly faster than
  25. transfers with older protocols.
  26.  
  27.  
  28. Credits
  29.  
  30. The protocol support code currently used in in xprquickb.library was
  31. originally written by Russ Ranshaw of CompuServe. It was then rewritten
  32. in C by Paul M. Resch (available as QUICKB.ARC in LIB 4 of the
  33. AmigaTech forum on Compuserve).  Jack Rouse modified it for Lattice C
  34. 5.04 and the XPR protocol.  Some of the supporting code was inspired by
  35. Rick Huebner's XPRZModem library, as was the option format. Willy
  36. Langveld of the Stanford Linear Accelerator Center (SLAC) developed the
  37. XPR interface.
  38.  
  39. Any bug reports for xprquickb.library should be directed to the
  40. Software Distillery.
  41.  
  42.  
  43. Use
  44.  
  45. To use the Quick B external protocol, you must have the file
  46. "xprquickb.library", which should be in this library.  This can be
  47. copied to one of system directories used with your communications
  48. program using the CLI command:
  49.  
  50.     copy xprquickb.library LIBS:
  51.  
  52. You must also have a communications program supporting XPR external
  53. protocols.   Versions of VLT since 4.036 support the XPR protocol.
  54. Versions of VLT since 4.226 support revision 2.0 of the XPR protocol,
  55. allowing downloads to be automatically initiated. The current version
  56. of A-Talk also supports XPR.
  57.  
  58.  
  59. You must select "xprquickb.library" from the external protocol menu of
  60. your communications program.  At this point, QuickB transfers can be
  61. initiated automatically (with communications program support) or
  62. manually via menu selections.  Various options are provided to control
  63. the operation of XprQuickB.  These are described later. The
  64. communications program may allow ongoing transfers to be aborted.
  65.  
  66. File transfers are initiated by actions on the host system (CompuServe).
  67. In general, file transfer will require an eight bit data connection.
  68. XprQuickB will attempt to put the communications program in eight bit
  69. mode.
  70.  
  71. The host sends a request to query file transfer capabilities and start
  72. the file transfer.  If the file transfer does not start automatically,
  73. you can request the communication program to go into file transfer
  74. mode.  This causes an dialog mode to be started within XprQuickB. This
  75. mode, provided for compatibility with older programs, is described in
  76. the following paragraphs.
  77.  
  78. The dialog mode requires the "xpr_gets" call-back function to be
  79. implemented. The communication program will ask for a file name.  Once
  80. the filename is entered, XprQuickB assumes a dialog must be initiated
  81. with the host to start the transfer.  XprQuickB will request the first
  82. line of the dialog, with the prompt "Startup line?". The requester may
  83. be seeded with the commands "dow/proto:qb" or "upl/proto:qb" which will
  84. request CompuServe perform a file transfer. Cancel the request if no
  85. first line is needed.
  86.  
  87. After the first line is sent, other interactions can occur with the
  88. host.  In particular, CompuServe will prompt for the file name on your
  89. computer.  XprQuickB transfers prompts (messages without line
  90. terminators) as communication program requesters, seeded with the
  91. previously entered file name.  If no host output occurs for 10 seconds,
  92. the transfer is aborted.
  93.  
  94.  
  95. Options
  96.  
  97. The behavior of XprQuickB can be configured through the options
  98. interface.  The exact details of this interface depends on the
  99. communications program, but the essentials are described below. 
  100. Consult the documentation of your communications program to determine
  101. how to access these options.
  102.  
  103. XprQuickB supports both string oriented and requester oriented option
  104. entry.  The string interface can be used with older programs, and to
  105. define default options when XprQuickB is loaded.  The requester
  106. interface is easier to use interactively.
  107.  
  108. The string option format corresponds to the format used with XprZMODEM.
  109. The option string consists of a series of "words", separated by spaces
  110. or commas.  Case is ignored.  The first character of each word
  111. identifies the option.  The second and following characters define the
  112. option value. All of the options below except I/O buffer size use only
  113. the first character of the option value.
  114.  
  115. The option descriptions below are headed by the option letter (in
  116. parenthesis), followed by the option description used with the
  117. requester interface.  Subheadings on the following lines describe the
  118. allowed option values.
  119.  
  120.     (T) Text mode
  121.     Y
  122.         Turn text character editing on.  On downloads, carriage
  123.         return and line feed pairs are turned into line feeds, the
  124.         standard Amiga line termination.  Also, characters following
  125.         a control-Z are ignored.  On uploads, carriage returns are
  126.         added before line feeds, which makes text more easily
  127.         portable to other machines.
  128.     N
  129.         Turns text character editing off.  All characters are passed
  130.         through as untranslated binary.
  131.     C
  132.         Consult the communications program to determine the text/
  133.         binary status.  XprQuickB defaults to binary transfer if the
  134.         communication program cannot assign a status,
  135.     H
  136.         Use the host's suggestion.  For uploads, text or binary mode
  137.         must be specified on the host command.  This is the default
  138.         value of the option.
  139.  
  140.     (O) Overwrite mode
  141.         Y
  142.         Silently overwrite existing files during downloads.
  143.     N
  144.         Avoid overwriting existing files.  This is done by
  145.         appending ".dup" or ".dupN" (for N a number from 2 to 99)
  146.         to the downloaded file name.  The new name will generally
  147.         appear in the file transfer status window.  If 99 ".dup"
  148.         files exist, ".dup99" will be overwritten.  This is the
  149.         default value of the option.
  150.     S
  151.         This option aborts the download if the file exists.
  152.  
  153.     (B) I/O buffer size (KB)
  154.         nnn
  155.         Here, "nnn" is a number representing the desired file buffer
  156.         size in multiples of 1024 bytes (KB).  This allows the disk
  157.         to be accessed less frequently.  A value of 0 disables file
  158.         buffering by XprQuickB.  The default is 16 KB.  The buffer
  159.         is allocated only during file transfers.  If the buffer can
  160.         not be allocated, XprQuickB uses no buffering.
  161.  
  162.     (A) Auto-activate transfers
  163.     Y
  164.         Setting this option on allows file transfers to be started
  165.         at the request of the host system.  This is the default.
  166.     N
  167.         This disables host initiation of transfers.
  168.  
  169.     (D) Delete after sending
  170.     Y
  171.         Turning this option on causes an uploaded file to be deleted
  172.         locally after a successful transfer.  The communication
  173.         program must support the "xpr_unlink" call-back function to
  174.         enable this option.
  175.     N
  176.         Uploaded files are retained.  This is the default.
  177.  
  178.     (K) Keep partial files
  179.     Y
  180.         Setting this option on causes the incomplete file from an
  181.         unsuccessful download to be retained.
  182.     N
  183.         Setting this option off causes the incomplete file to be
  184.         deleted.  The deletion occurs only if the "xpr_unlink"
  185.         call-back is supported.  This is the default (if
  186.         "xpr_unlink" is available).
  187.  
  188.  
  189. Compiling
  190.  
  191. XprQuickB was compiled with Lattice C 5.04.  This simplifies the shared
  192. library interface, avoiding stub routines.  The supplied "LMKFile"
  193. compiles and links the library.  Note that the code must be compiled
  194. with the "-ml" and "-v" options.
  195.  
  196.